ADA Programming Guide/ADA Programming Guide.iso/ada_gwu/userman.dos

Text File | 1996-01-30 | 32KB | 738 lines

              GWAda Program Development Environment
              -------------------------------------
                      User Manual
                      January 1994

                Prof. Michael B. Feldman
           Department of Electrical Engineering and Computer Science
          The George Washington University Washington, DC 20052
                 [phone] (voice)
                  [phone] (fax)
                [e-mail] (Internet)













     This project was sponsored by The George Washington University, and in
     part by the United States Advanced Research Projects Agency (ARPA)
     under contract #FY3592-93-10234, administered by Phillips Laboratory,
     Kirtland AFB, NM 87117-5776.


     Copyright (C) 1993,
     Charles W. Kann, Arthur Vargas Lopes, and Michael Bliss Feldman


     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


     GWAda User Manual                January 1994                     page 1


     I. ABOUT THE GWAda DEVELOPMENT ENVIRONMENT

     GWAda is a development environment built around the NYU AdaEd
     compiler/interpreter. It allows the  editing,  compiling,  binding  and
     execution of Ada 83 programs.

     GWAda was supervised by Prof. Michael B. Feldman. Dr. Arthur V. Lopes
     wrote the editor and associated tools; Charles A. Kann, a GWU doctoral
     student in Computer Science, is responsible for the run-time monitoring
     capabilities.

     GWAda User Manual                January 1994                     page 2


     II. INSTALLATION

     When you un-archive the files (see the instructions below), you will
     find a user manual, userman.doc, describing the GW development
     environment, and a file readme.nyu file with documentation on the NYU
     part of the system. Note that you do not have to use the GWAda
     integrated environment, but can execute the various parts of NYU Ada/Ed
     from the DOS command line, as described in the NYU instructions.


     System Requirements
     -------------------

     IBM PC Compatible, 386 or 486, running MS-DOS or PC-DOS
     at least 3.6 mb available extended memory
     at least 5   mb free hard disk space


     Installing GWAda
     ----------------

     Assuming that:

     first diskette is in drive B:
     the target hard disk is C:

     1 - The installation process will create a directory named ADAED
     to store everything, so first position to the desired hard disk.

       cd C:\

     2 - Copy unzip.exe from the diskette to the hard drive

       copy b:\unzip.exe .

     3 - Unzip the first archive

       unzip b:\support.zip

       then change to the adaed directory, replace the first diskette with
       the second, and type

       c:\unzip b:\binaries.zip

     4 - Create a working directory for your Ada programs:

       mkdir c:\adaed\myprogs

     5 - Add c:\adaed to your DOS path, for example

       path=c:\adaed;c:\;c:\dos


     GWAda User Manual                January 1994                     page 3


     6 - create the adaed environment variable:

       set adaed=c:\adaed

       You might wish to add steps (4) and (5) to your autoexec.bat file, or
       create a separate setup.bat just to run when you need to use GWAda.

     7 - Change to your working directory

       cd c:\adaed\myprogs


     GWAda User Manual                January 1994                     page 4


     III. USING GWAda

     This section gives a tutorial on using GWAda.


     A First Compilation and Execution using GWAda and Runtime Monitoring
     -------------------------------------------------------------------

      1 - Copy the Ada demonstration programs from the directory
      \ADAED\GWUDEMOS to your working directory

       copy \adaed\gwudemos\*.* .

      2 - Start GWAda by typing "GWAda FIRST.ADA"

      3 - The GWAda editor should now be running, with the source for
      the program FIRST.ADA in the window.  First, create a new
      library as follows:

      Press the ESC key to put the menu bar at the top of the screen.
      Type O to select the options menu.
      Type N to select a new library.

      A New library has been created.

      4 - You should still be on the menu bar. Type C to select compile, then
      C again to indicate that the file in the current window is to be
      compiled.

      5 - When the compilation is done, you will no longer have the menu bar.
      Press the ESC key to bring up the menu bar, and type B to bind
      (link) the program.

      6 - You will be asked for the program to bind.  Select "first" by
      pressing ENTER. The program is now bound (linked).

      7 - Type R to run the program.  When asked which program to run, select
      "first".

      8 - You should now have up the monitor screen.

      9 - Press ESC to take the default options on the first screen
      (speed = 6, exceptions = yes, and tasks = no). Press ESC again to
      take the defaults on the second screen (Small window, line
      tracing, and no procedure tracing).

     10 - Now the monitor should be running, stopped at the elaboration of
      the variable Name.  Press the space bar until the program asks for
      your name, then once more so that it will reach the Get_Line
      statement.  Type in your name, then press return.  Continue to
      press the space bar until the program completes execution.

     GWAda User Manual                January 1994                     page 5


     Compiling a Program That Isn't in the Current Window
     ----------------------------------------------------

     To use the rest of the demo programs, you will need to compile some
     input/output instances. These are in the file IO_LIBS.ADA. Press ESC
     to reveal the menu bar, then C to request compilation, then select
     "select unit" to select a file from the working directory. You will get
     a window showing the directory followed by *.ADA. Press ENTER; you will
     then see a window showing all the files with file type .ADA. Use the
     down-arrow key to select IO_LIBS.ADA; this file will then be compiled.


     Using the GWAda Runtime Monitor to Trace Subprogram Calls
     ---------------------------------------------------------

     To demonstrate subprogram tracing we use the program FIBB.ADA. This
     program calculates a Fibonacci number by summing the two previous
     Fibonacci numbers. The Fibonacci series is

     1 1 2 3 5 8 13 21 ...

     It was developed originally to model the growth of a colony of rabbits.
     The Fibonacci function is recursive, so running the program will lead
     to a large number of nested recursive calls. Compile this program,
     then bind it as before.

     To see the execution tracting, take the default options on the first
     Run screen (speed = 6, exceptions = yes, and tasks = no)
     Change from a Small Window to a Large Window on the second screen.

     The purpose of this program is to show a large amount of recursion.
     Therefore, when prompted for the number to be calculated, choose 7.
     This will cause Fib_Calc to be called recursively many times..

     Notice that each time Fib_Calc is called, a new window is opened until
     the screen is filled with windows.  At that point, no new windows are
     created, but notice that the highest level window "Scrolls" off to the
     upper right and is no longer visible.

     When the program has gotten to the final window, notice how it begins
     to scroll the windows back on to the screen as the call stack unwinds.
     When all the programs on the stack are back on the screen, the stack
     continues to unwind, until there is only a single procedure left on
     the screen.  This shows the call stack, and the recursion of the program.

     You can control the speed of execution by pressing the up-arrow (faster)
     or down-arrow (slower) keys. Note how the "speedometer" shows the speed.


     GWAda User Manual                January 1994                     page 6

     Running a Program without the Monitoring
     ----------------------------------------

     If you wish simply to execute a program without the line and procedure
     tracing, select the Options menu (alt-O), then select Parameters (Run)
     (press P) and then select Monitoring (1). You will then see a window
     open. Press 1 and you will see the line "source line monitoring" change
     from On to Off. Then press ENTER to leave the window and ESC to close
     the Options menu.

     Now run Fibonacci as before. You will see the program output on the screen
     without the monitoring.


     Compiling Some Useful Ada Packages
     ----------------------------------

     Before we proceed with the demonstrations, let's compile two useful
     packages: Random, which provides pseudo-random numbers, and Screen, which
     allows the screen cursor to be moved to an arbitrary position. Because a
     package in Ada has two parts, a specification and a body, we must do two
     compilations for each package. In the demonstrations, the file type .ADS
     is used to indicate a spec, .ADB to indicate a body. Give yourself some
     practice in compilation by compiling RANDOM.ADS and RANDOM.ADB, then
     SCREEN.ADS and SCREEN.ADB. These are not bindable; they are packages, not
     programs.

     You can select List Library from the Options menu to see the results of
     all these compilations.


     Programs with Multiple Tasks
     ----------------------------

     To illustrate multiple tasks in GWAda, we use the program WORMS.ADA.
     This program is based on a UNIX game called worms. It is especially
     interesting because the Worms program could really be implemented as a
     sequential program. This implementation shows how tasks can be used to
     simplify the design of a sequential program. By defining the Worms as
     individual tasks, the programmer only has to worry about defining the
     behavior of a single Worm, and then creating multiple Worm objects.

     First we need to compile two more packages: SCREENIO.ADS and SCREENIO.ADB,
     which takes care of screen handling in a multitask situation, and
     CREATURE.ADS and CREATURE.ADB, which defines the worm creatures.

     Now with the monitor still off, compile and bind WORMS.ADA. When the
     program is executed, it will ask you how many worms you'd like, and
     also the screen boundaries. Enter 1 1 80 24 to the screen-boundary prompt.

     Now run the program. You will soon see worm creatures squiggling randomly
     around the screen.

     Now turn monitoring on (Options menu, remember?), and run Worms again.

     GWAda User Manual                January 1994                     page 7


     On the initial monitor setup screen, choose Y to the question whether tasks
     are used.  Also, set the initial speed to 10, the fastest speed. You will
     notice when you start the program that because of the monitoring, the
     worms move MUCH more slowly on the screen. But the first four windows which
     show up will let you see the main procedure WORMS, the task SCREEN, and two
     instances of the WORM creature.  Notice how the WORM tasks interact with
     SCREEN.


     Another Tasking Program
     -----------------------

     Compiling ELEVATOR.ADA and ELEVDEMO.ADA will show you a simulation of a
     two-elevator system in an office building. Try this with and without the
     monitor.

     GWAda User Manual                January 1994                     page 8


     IV. THE GWAda MULTI-FILE EDITOR

     Here you will find a summary of the operations allowed by the GWada multi
     text full screen editor.
     The GWAda top menu becomes visible by depressing either the F10 or ESC key.

     The editor works under two modes of operation:
      -Insert (Ins)
      -Overwrite (Ovr)
     with up to 8 text files.

     You may perform cut and paste operations among any of the 8 text files.
     To open a text file depress the Alt-F O keys. To flip among open text
     files use the Alt-W keys.

     To close the current text file use the Alt-F C  keys. The current text
     file is the file whose portion is being displayed onto the screen.
     The above operations may also be performed by using the top menu. The top
     menu is activated by depressing the F10 key. To  return  to  the  editing
     mode depress the ESC key.
     The operations allowed are shown below:

       Key      Description/Action (Upper and lower case letter keys have
          equal meaning)

       Arrow    Allow to move the cursor left, right, up and down.
       PgUp     Moves the cursor one page up.
       PgDn     Moves the cursor one page down.
       Home     Moves the cursor to the text line begin.
       End      Moves the cursor to the text line end.
       Ctrl-V
       Ins      Changes from Ins mode to Ovr mode, and
          from Ovr mode to Ins mode.
       Del      Deletes the current character.
       Backsp   The backspace key to the left of the current character.

       Ctrl-N
       ENTER    Creates a new line.
       Tab      Insert up to 4 spaces according to the cursor location.
        The default indentation size is 4. It can be altered in
          the Options top menu (Alt-O I).
       F1       Help on Hot Keys.
       F5       Go to a specific text line (user is prompted).
       F7       Generates a package body skeleton from a compiled package
          specification. Before depressing the F7 key first position
          the cursor over the PACKAGE keyword that starts a given

     GWAda User Manual                January 1994                     page 9


          package specification. Only then depress the F7 key. You
          will be prompted for the name of the file that will
          contain the resulting package body skeleton. You can then
          open the package body file and complete the various
          subprogram bodies.
        While this option performs some syntax check, It is assumed
          that the package specification is correct. If so, the
          stubs or skeletons of the subprograms will all be legal;
          the package body skeleton will compile without errors.
       ESC
       F10      Brings the GWAda Development Environment Menu (Top Menu).
       ESC      Returns to the editing mode from the Top Menu

       Ctrl-y   Deletes the current line (identical to Alt-E D);
       Ctrl-g   Deletes current character (identical to Del key);
       Ctrl-k b Mark text's block begin (identical to Alt-E M).
          without holding the Ctrl key.

       Ctrl-k k Mark text's block end (identical to Alt-E M).
       Ctrl-k c Copy previously marked block (same as Alt-E  C);
       Ctrl-k s Saves the current file.

       Ctrl-D   Moves right.

       Ctrl-Left
       Ctrl-A   Move back one word.

       Ctrl-Right
       Ctrl-F   Move forward one word.

       Ctrl-Q R Move to begin of file.
       Ctrl-Q C Move to end of file.
       Ctrl-Q Y Delete from the current position to the line's end.

       Alt-F
       F2       Activate File menu

       Alt-F O  Opens a file for editing.
       Alt-F C  Closes the current file being edited.
       Alt-F S  Save the text to disk.
       Alt-F I  Shows general information.
       Shift-F9
       Alt-F D  Starts a DOS shell.
       Alt-F Q  Quits the program.
       Alt-F4   Quits the program.

       Alt-E    Activate Edit menu
       Alt-E I  Inserts a text file to the right of the current
          cursor location.
       Alt-E D  Deletes the current line.

     GWAda User Manual                January 1994                    page 10


       Alt-E F  Scans the text looking for the first occurrence of a string.
       Alt-E R  Perform text replacement.
       Alt-E M  Used to mark a block of text for future duplication or
          disk transfer.
       Alt-E C  Inserts a previously marked text block.
       Alt-E W  Creates a disk file containing a previously marked text
          block.
       Alt-E S  Allows the insertion of special ASCII symbols.

       Alt-C    Activate Compile menu
       Alt-C C  Compile the current text file
       Alt-C S  Select a non editing text file for compilation

       Alt-B    Activates the Bind menu

       Alt-R    Activates the Run menu

       Alt-W    Activates the Window menu
       Alt-W n  Sets the text file name, n, as the current editing file.

       Alt-O    Activates the Option menu
       Alt-O D  Used to set the source file and library directory.
       Alt-O M  Access the monitoring/debugging tools.
       Alt-O F  Used to set compiler and interpreter options.
       Alt-O C  Allows to customize the editor/environment colors.
       Alt-O I  Used to set the indentation size (default = 4).
       Alt-O R  Reads in the options file previously saved.
       Alt-O W  Saves to disk the current options.
       Alt-O S  Overwrite current options with the default options.

       Alt-A    Activates the Ada menu.
         Here you will find skeletons or templates for various
         Ada structures. You are invited to explore these.

     GWAda User Manual                January 1994                    page 11


     V. GWUMon: THE GWAda RUNTIME MONITORING SYSTEM

     Running from the Command Line
     -----------------------------

     Although GWUMON was written to be integrated into GWAda, it can be run
     standalone from the command line.  If you wish to do this, you should make
     sure that all your compiles include the "-a" option, ie:

     adacomp -a -b first.ada

     When you run GWUMON, the command line options are exactly the same as
     the options for "adaexec", so you should check the NYUAda documentation if
     you wish to set these options.  Note that if you don't set the "-a" option
     in the compile, the monitor will NOT work!


     Running from GWUAda
     -------------------

     If you are running GWUMON from GWAda, you do not have to worry about
     any compile options, etc.  GWAda sets them for you.  From the command line,
     type "GWAda", and the GWAda system will start up.

     To run the monitor from GWAda, go to the options menu, and choose the
     option "Run Monitor".  This is a toggle which turns the monitor on and off.
     If you choose not to run the monitor, the NYU AdaExec program is run as
     usual from GWAda.


     GWUMon Options
     --------------

     There are many options which can be set in GWUMON.  The best way to
     find out what they all are is to experiment with the system.  There are
     several programs distributed with the monitor which will help to give
     the user some experience with using the monitor.  It is suggested that the
     user try these programs to see how the monitor works.

     This section will give an overview of what options are available in GWUMON,
     and how they work.  This is given mainly as a reference; the user should
     try these options to see how they work.


     Initial Setup Screen

     When GWUMON begins execution, the Initial Setup screen is brought up.
     This screen is only brought up once per run, when GWUMON starts to run.
     It has the following three options:

     1 - Execution Speed - This is the initial speed of the program
     when it starts to run.  It is relative to the maximum

     GWAda User Manual                January 1994                    page 12


     speed of the monitor.  Once the monitor has started
     running, the up/down arrow keys are used to adjust the
     speed of the monitor.

     2 - Exception Tracing - This determines whether or not exceptions
     will be traced when the monitor is running.  If this option
     is set to no, unhandled exceptions are not reported.

     3 - Does your program use tasks - This question determines how the
     monitor runs.  The monitor has two modes, one which is used
     for sequential programs, and one which is used for concurrent
     programs (ie. programs which use tasks).  These two modes are
     incompatible (ie. programs which have tasks should not be
     run in sequential mode, and vice versa).  Since the monitor
     cannot determine before execution if the program uses tasks
     or not, it is up to the user to set this option correctly.


     Sequential Setup Screen

     If the user has selected Sequential Execution (ie. no tasks are used),
     then the next menu to come up will be the Sequential Setup menu.  This menu
     can also be brought up by using the F10 key when the program is running in
     sequential mode. This menu has the following options:

     1 - Monitor Window Size - This option selects how large to make the
     monitor window.  If the small window is chosen, the program
     output window is made larger.  If the large window is chosen,
     the program output window is made smaller (just 2 rows).  This
     option should be chosen based on how much of the program
     output should be seen, verses program source code.

     2 - When to Pause Execution - This determines when the monitor
     will pause execution and wait for the users' input to
     allow it to continue.  The options here are:

     As a Program Enters/Exits Procedures - If this option is
     set to "Y", then each time a block is entered or exited, the
     program will pause for user input.

     As Each Line Of Code Is Executed - If this option is set to
     "Y", then each time a line of code is run, the program will
     pause for user input.  Note that a line of code could
     represent more than 1 p-code statement.


     Tasking Setup Screen

     If the user has selected Concurrent Execution (ie. tasks are used),
     then the next menu to come up will be the Tasking Setup menu.  This menu
     can also be brought up by using the F10 key when the program is running in
     tasking mode. This menu has the following options:

     GWAda User Manual                January 1994                    page 13


     1 - General Information

     1.1 - What do you want to monitor - The user can monitor
     either the lines as they are executed, execution profile
     for the tasks, or nothing.

     1.2 - Type of Delay - This option has not yet been implemented.

     1.3 - Tasking Model - This deals with the type of tasking.
     This can either be "Run Til Blocked" (ie. continue to run
     until the task gives up the CPU) or Round Robin (ie. each
     task runs until it's quantum is used up).

     1.3.1 - If the tasking model chosen is round robin, then
     the size of the quantum must be set.  This is the number of
     p-code statements are executed between a task switch.

     2 - If option 1.1 was chosen to monitor lines, then these options
     are set.

     2.1 - Type of Monitor Window - This determines how many
     tasks can be seen on the screen at a time, and the type of
     windows that display those tasks.

     2.2 - When to Pause Execution - This determines when the
     monitor will pause execution and wait for the users' input
     to allow it to continue.  The options here are:

     As a Program Enters/Exits Procedures - If this option is
     set to "Y", then each time a block is entered or exited, the
     program will pause for user input.

     As Each Line Of Code Is Executed - If this option is set to
     "Y", then each time a line of code is run, the program will
     pause for user input.  Note that a line of code could
     represent more than 1 p-code statement.

     3 - If option 1.1 choose to profile the program, then the number
     of p-code statements which are executed between reports of
     the profile report is set here.


     Control Screen

     The Control Screen allows the user to choose which tasks they wish to
     see on the screen when the monitor is running.  It tells the current
     status of the tasks, and allows the user to choose which tasks they
     wish to monitor.  The field WON tells which windows are currently being
     monitored, if the field is "yes", the task is attached to a monitor
     window.  This WON field can be toggled by using the arrow keys to
     position yourself on the task you want to change, and typing the "t"

     GWAda User Manual                January 1994                    page 14


     key.

     If there are more then one screens worth of tasks, then hitting the down
     arrow on the last task on the screen will bring up the next series of
     tasks.


     Options When Line Monitor Is Running
     ------------------------------------

     Line monitoring allows the user to see what lines are being executed
     in each task as they are running.

     Many of the options which are available from the SETUP screen which
     pertain to line monitoring can be set with a single key stroke while the
     monitor is running.  This is to save the user the time of having to
     go into the SETUP screen and change the options.  These commands are
     summarized here:

     Up Arr - doubles the speed of the interpreter (ie. cuts the
          delay in half.)
     Dn Arr - halves the speed of the interpreter (ie. doubles the
          delay.)
     ctrl a - brings up the control screen to allow the user to
          set the tasks they would like to monitor.
     ctrl b - stops the monitor from running.  This options allows the
          user to run their program without any monitor output.  Note
          that the delay still is in effect, and the program can be
          slowed down or sped up.
     ctrl c or ESC - stop the execution of the monitor.
     ctrl d - Brings up the setup screen.
     ctrl h - Brings up the help screen.
     ctrl l - Sets line step mode, where the monitor stops after each
          line that is in a currently active monitor window has been
          executed.
     ctrl t - Sets line task step, where the monitor stops after each
          task switch that is in a currently active monitor window
          has been executed.


     Execution State Codes
     ----------------------

     The state codes for tasks during line monitoring are as follows:

     R - Wait on Rendezvous      M - Rendezvous Meet
     D - Wait on Delay           * - Task Ready to Run
     --> Task currently running


     Note that all this information can be obtained by typing "CTRL-H" when
     the line monitor is running.

     GWAda User Manual                January 1994                    page 15


     Execution Percentage Window
     ---------------------------

     The executions percent window allows the user to compare the relative
     number of clock cycles each task uses.  The only option on this
     window is to turn the monitoring by using the CTRL-B key.


     Known Bugs and Other Hints
     --------------------------

     There are a number of known bugs and problems which can occur when
     using the monitor.  These will be fixed for the next release.

     1 - Too many key strokes which are not processed can cause the
     monitor to hang.  For example, if you hit a lot of DOWN ARROW
     keys to slow the monitor down, the system will take longer to
     process these keys, and eventually will hang.  If this happens,
     the computer must be rebooted.

     2 - The monitor comes up but no source lines are displayed and
     the task line is not advanced.  This can be caused by the
     source program not being compiled with the "-a" option.  If
     you are compiling from the command line, make sure you use
     the "-a" option on the compile.

     Note that this will not happen if the monitor is run from
     GWAda.

     3 - There are some memory problems in using GWAda under DOS,
     specifically, if you try to load DOS high without a memory
     manager, GWAda will be unable to spawn processes.  This will
     result in an error in using DOSX.  If you have this problem,
     either remove the "DOS=HIGH" statement from your config.sys,
     or install a memory manager such as QEMM or EMM386.

     4 - GWAda runs under a DOS shell from either Windows or OS/2.
     If you have any problems, check the amount of memory and
     memory settings.  In particular, GWAda has problems if not
     enough memory is specified for Windows.

     5 - If you are a user of a previous version of GWAda, make sure
     that you create a new library before you use this new version of
     GWAda.  Some changes were made in the library format to handle
     the monitoring.  These make libraries made with older versions
     of GWAda incompatable with the current libraries.  This will show
     up in the occurance of "chaos" messages.